Directing the Buffer Clobber Event

Directing the Buffer Clobber Event

An X client can ask to receive GLX events on a window or GLXPbuffer by calling glXSelectEventSGIX():

void glXSelectEventSGIX(Display *dpy, GLXDrawable drawable,
                       unsigned long mask)

Currently you can only select the GLX_BUFFER_CLOBBER_BIT_SGIX GLX event as the mask. The event structure is

typdef struct {
  int event_type;           /* GLX_DAMAGED_SGIX or GLX_SAVED_SGIX */
  int draw_type;            /* GLX_WINDOW_SGIX or GLX_PBUFFER_SGIX */
  unsigned long serial;     /* # of last request processed by server */
  Bool send_event;          /* true if it came for SendEvent request */
  Display *display;         /* display the event was read from */
  GLXDrawable drawable;     /* i.d. of Drawable */
  unsigned int mask;    /* mask indicating which buffers are affected*/
  int x, y;
  int width, height;
  int count;                /* if nonzero, at least this many more */
} GLXBufferRestoreEvent;

A single X server operation can cause several buffer clobber events to be sent, for example, a single GLXPbuffer may be damaged and cause multiple buffer clobber events to be generated. Each event specifies one region of the GLXDrawable that was affected by the X server operation.

A mask argument to glXSelectEventSGIX() indicates which color and ancillary buffers were affected. All the buffer clobber events generated by a single X server action are guaranteed to be contiguous in the event queue. The conditions under which this event is generated and the event type varies, depend on the type of the GLXDrawable:

For a preserved GLXPbuffer, a buffer clobber event, with type GLX_SAVED_SGIX, is generated whenever the contents of the GLXPbuffer are swapped out to host memory. The event(s) describes which portions of the GLXPbuffer were affected. Clients who receive many buffer clobber events, referring to different save actions, should consider freeing the GLXPbuffer resource to prevent the system from thrashing due to insufficient resources.
For a volatile GLXPbuffer, a buffer clobber event with type GLX_DAMAGED_SGIX is generated whenever a portion of the GLXPbuffer becomes invalid. The client may wish to regenerate the invalid portions of the GLXPbuffer.
For windows, buffer clobber events with type GLX_DAMAGED_SGIX or GLX_SAVED_SGIX occur whenever an ancillary buffer associated with the window is clobbered or swapped out to host memory. The event contains information indicating which color and ancillary buffers--and which portions of those buffers--were affected.

Calling glXSelectEventSGIX() overrides any previous event mask that was set by the client for the drawable. Note that it does not affect the event masks that other clients may have specified for a drawable, since each client rendering to a drawable has a separate event mask for it.

To find out which GLX events are selected for a window or GLXPbuffer, call glXGetSelectedEventSGIX():

void glXSelectEventSGIX(Display *dpy, GLXDrawable drawable,
                       unsigned long mask)